package org.abettor.jroa;

import java.io.IOException;
import java.util.Properties;

/**
 * <p>An interface which sepecific the form of the driver who implements JROA.</p>
 * 
 * @author <a href="http://www.abettor.org" target="_blank">abettor</a>
 *
 */
public interface Driver
{
	/**
	 * Test if the <i>url</i> is supported by the driver.
	 * @param url
	 * <p>A string to specify the type of the driver's implemention
	 * and the network address.</p>
	 * <p>The format of the <i>url</i> can be <b>jroa:DRIVER_TYPE://ADDRESS/SUBTYPE</b>.</p>
	 * @return
	 * True if the <i>url</i> is supported while false for otherwise.
	 */
	public boolean support(String url);

	/**
	 * Establish a connection with the specific address of the <i>url</i>.
	 * @param url
	 * <p>A string to specify the type of the driver's implemention
	 * and the network address.</p>
	 * @param prop
	 * <p>A set of properties to parse by the driver when establishing a connection.</p>
	 * @return
	 * <p>If successed to establish a connection, the <i>Connection</i> object will
	 * be returned. Otherwise, null will be returned.</p>
	 * @throws IOException
	 * @throws UrlNotSupportException
	 * @throws AuthenticationException
	 */
	public Connection connect(String url, Properties prop)
		throws IOException, UrlNotSupportException, AuthenticationException;

	/**
	 * <p>Bind on an address specified by <i>url</i> for accepting connections.</p>
	 * <p>Note that a <i>Driver</i> object should call this function for only once.</p>
	 * @param url
	 * <p>A string to specify the type of the driver's implemention
	 * and the network address.</p>
	 * @return
	 * <p>If successed to bind and create a service listener,
	 * it returns a <i>Acceptor</i> object. Otherwise, null is returned.</p>
	 * @throws IOException
	 * @throws UrlNotSupportException
	 */
	public Acceptor bind(String url) throws IOException, UrlNotSupportException;
}
